home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / c / dice-3.16.lha / doc / wedge.doc < prev   
Text File  |  1994-02-13  |  24KB  |  609 lines
  1.  
  2.                 WEDGE
  3.  
  4. Format: WEDGE <library> <offset> [regs ptrs] [opt fklnprasxz u t=<tasklist>
  5.         b=<baud> c=<comment> d=<n>]
  6.     or  WEDGE LIST
  7.     or  WEDGE KILLALL
  8.  
  9. Template: WEDGE "LIBRARY,OFFSET,REGS/K,PTRS/K,OPT/S,T=/K,B=/K,C=/K,D=/K"
  10.  
  11. Purpose: To monitor calls to any library function.
  12.  
  13. Specification:
  14.  
  15. WEDGE allows you to monitor the library function calls of system and
  16. application tasks.  This is useful for both debugging and the optimization
  17. of software. WEDGE reports the name and address of the task calling the
  18. function, the Forbid/Disable status, the register contents, data pointed to
  19. by registers, stack, and the function return value.
  20.  
  21. You can restrict reporting to a list of tasks, and you can also exclude a
  22. list of tasks from reporting.  When in serial mode, Debug (ROMWACK) can be
  23. invoked either before or after the WEDGEd function.
  24.  
  25. Wedge 37.1 adds SegTracker support, and reduced stack usage.
  26. (older versions of wedge can cause stack overflow crashes under
  27. 2.1 and higher OS when locale.library is present).
  28.  
  29. NOTE - The new Software Tools LVO command has a "wedgeline" option which
  30. can be used with the Amiga FD files to automatically create command lines
  31. for WEDGE.  This is the easiest way to create a basic command line for
  32. WEDGE - much easier than figuring out the register bit patterns yourself.
  33. See the final section on creating your own wedges for more information.
  34.  
  35.  
  36. EXPLANATION OF WEDGE ARGUMENTS
  37.  
  38. In this section, the CLI argument is listed followed by the Workbench TOOL
  39. TYPE enclosed in parentheses.  If an example is included to illustrate an
  40. argument, the example shows both the CLI argument and the corresponding TOOL
  41. TYPE.
  42.  
  43.  
  44. Required Arguments (ToolTypes shown in parentheses)
  45.  
  46. NOTE - All command line options should be lower-case
  47.  
  48. <library> (LIBRARY=)    Specifies any run-time library (without the
  49.             ".library" suffix).
  50.  
  51.             Example:    exec        (LIBRARY=exec)
  52.  
  53.  
  54. <offset>  (OFFSET=)    Specifies the library base offset of the function
  55.             being WEDGEd.  It must be expressed as a negative
  56.             offset in hexadecimal form.
  57.  
  58.             Example:    0xff28    (OFFSET=0xff28)
  59.  
  60.  
  61. Optional Argument Pair
  62.  
  63. NOTE:  REGS and PTRS must be used in conjunction with each other.  If you
  64.        supply one option, you MUST supply the other.  They cannot be used
  65.        alone.
  66.  
  67. <regs>    (REGS=)        Hexadecimal word (format 0xHHHH) representing the
  68.             registers that should be reported.  Each bit set in
  69.             the word represents a 68000 register, with the bits
  70.             from right to left, representing d0 through d7 then
  71.             a0 through a7.
  72.  
  73.             Example: To monitor d0, d1, a0 and a6, the bit
  74.                  pattern would be:
  75.  
  76.                                          a6        a0    d1  d0
  77.                                           \        /      \  /
  78.                                  Binary:  0100 0001 0000 0011
  79.  
  80.                              Then convert binary nibbles to hexadecimal:
  81.  
  82.                                   Binary<>Hex Conversion Table
  83.  
  84.                                  0000=0  0100=4  1000=8  1100=C
  85.                                  0001=1  0101=5  1001=9  1101=D
  86.                                  0010=2  0110=6  1010=A  1110=E
  87.                                  0011=3  0111=7  1011=B  1111=F
  88.  
  89.                  This example converted to hex is
  90.  
  91.                                               HEX 4 1 0 3
  92.  
  93.                                  The regs argument would be:
  94.  
  95.                  0x4103        (REGS=0x4103)
  96.  
  97.  
  98. <ptrs>    (PTRS=)    The hex word (format 0xHHHH) representing the
  99.             monitored registers that point to the data you want
  100.             reported.  This is especially useful for monitoring
  101.             text strings passed as function arguments. The first
  102.             16 bytes of the data will be reported in both hex
  103.             and ASCII.  The hex word is formed the same way as
  104.             for the REGS option.
  105.  
  106.             Example:  If d1 and a0 are pointers:
  107.                     0x0102    (PTRS=0x0102)
  108.  
  109.  
  110.  
  111. f      (FORBID=TRUE)    Causes WEDGE to Forbid() before calling the WEDGEd
  112.             function.  WEDGE will not call Permit() until Result
  113.             is returned.  This flag is only meaningful if Result
  114.             reporting is in effect.  When you are monitoring
  115.             tasks that are calling the same functions, this flag
  116.             can help to synchronize Result reports with other
  117.             WEDGE output by attempting to prevent multitasking
  118.             until the function returns.  Functions that Wait()
  119.             and local output will break this Forbid().
  120.  
  121.  
  122. k    (KILL=TRUE)    Kills this WEDGE.  Use KILL=TRUE for a kill-only
  123.             icon.  Use KILL=FALSE for an install-only icon.  If
  124.             a KILL TOOL TYPE is not present, the icon will
  125.             toggle WEDGE in and out.)
  126.  
  127.  
  128. l      (LOCAL=TRUE)    Selects studio reporting.  In this mode, WEDGE can
  129.             only report the function calls of non-FORBIDden
  130.             processes with available stack of at least 1800
  131.             bytes.  (Only 300 bytes are needed for serial or
  132.             parallel output.)  In addition, function calls made
  133.             by the Local output handler will not be reported.
  134.             (The Local output handler is usually a window, but
  135.             it may be another handler if CLI output redirection
  136.             was used.)
  137.  
  138.             In all output modes, WEDGE will bypass reporting if
  139.             the caller's available stack is too low for safe
  140.             execution of the output function.  All unreported
  141.             calls are tallied, and a count is presented at the
  142.             next report. The available stack safety feature may
  143.             be turned off (at your own risk) with the UNSAFE
  144.             TOOL TYPE or with the CLI 'U' flag.
  145.  
  146.  
  147. n    (NOISY=TRUE)    Notifies user of WEDGE installation and removal.
  148.  
  149.  
  150. p    (PARALLEL=TRUE) Selects parallel reporting, instead of serial.  By
  151.             default, all debugging output is directed to the
  152.             serial port and may be received by a terminal,
  153.             serial printer or a second computer running terminal
  154.             software.  Optionally, the output can be directed to
  155.             the parallel port or displayed locally.
  156.  
  157.  
  158. r    (RESULT=TRUE)   Monitors the return value of reported functions. An
  159.             Id number is assigned to each reported function
  160.             call.  That call's Return value report is tagged
  161.             with the same Id number. This allows you to match
  162.             calls and return values, even if multitasking causes
  163.             other WEDGE reports to be output in between them.
  164.  
  165. a    (RESULTP=TRUE)    Monitors what the result points to.
  166.  
  167.  
  168. s    (STACK=TRUE)    Monitors stack limits and pointer.
  169.  
  170.  
  171. x    (EXCLUDE=TRUE)    Excludes tasks in the tasklist from reporting.
  172.  
  173.  
  174. u    (UNSAFE=TRUE)    Reports regardless of the available stack.  Use this
  175.             option at your own risk.  When WEDGE is run from the
  176.             CLI, the U flag may not be grouped with other flags
  177.             (there must be a space before it).
  178.  
  179.  
  180. z    (ZAP=TRUE)    When used in conjunction with the k option, z lets
  181.             you force the unloading of a WEDGE that is still in
  182.             use.  Generally this is a very dangerous thing to
  183.             do.  But, occasionally, it is necessary because a
  184.             WEDGE that is unWEDGEd with kill will not be
  185.             unloaded if there is still an "occupant" in the
  186.             WEDGE. This can occur if you have WEDGEd Wait() with
  187.             Result reporting, and a task calls Wait(0), which
  188.             will never Return.  In this case, you can use the z
  189.             option to force the unloading of the Wait() WEDGE.
  190.             Note:  A new WEDGE may not be installed in a
  191.             function if an old one has not been unloaded.
  192.  
  193.                 Usage -- CLI:  Opt KZ
  194.                          TOOL TYPES:    KILL=TRUE
  195.                               ZAP=TRUE
  196.  
  197.  
  198. "b=rate"  (BAUD=RATE)    Sets the serial hardware baud rate.  This option is
  199.             ignored if Parallel or Local output is requested.
  200.             The baud rate is determined by the last value stored
  201.             in the serper register. When you boot your system,
  202.             the hard ware is set to 9600 baud.  If you use the
  203.             serial.device or SER: before using WEDGE, the serper
  204.             (serial period) register may contain a different
  205.             rate.  Use this option to reset the baud rate for
  206.             WEDGE.  If run from CLI, the b option without a
  207.             specified rate will set 9600 baud.  If you also use
  208.             the d option to enter ROMWACK, you must use 9600
  209.             baud since ROMWACK forces 9600.  Use quotes if you
  210.             are passing this parameter to a script.
  211.  
  212.  
  213. "c=text" (COMMENT="text") Allows you to include a comment with each report.
  214.              The comment is generally the name and register
  215.              argument descriptions for the function being
  216.              WEDGEd.  From CLI, quotes must be used around the
  217.              entire C= string if the comment contains spaces.
  218.              If entered from the Workbench, ev